Library: BSXdocumentationUtils

VSID.BSXdocumentationUtils

Created Jun 2022 by Devin Olson/USA/PNPHCL
	BaliSX Documentation Utilities

Library Summary

Script Creator Devin Olson
Uses Libraries baliListsCollections, enhLogClassLite

Script Creator	Devin Olson
Uses Libraries	baliListsCollections, enhLogClassLite

Constants

Name	Value	Comment
`Public APIDOC_VERSION`	`\|1.0.0\|`
`Public ERR_INVALID_SIGNATURE_CODE`	`1195`
`Public FOLDERNAME_APIDOC`	`\|apidoc\|`
`Public FOLDERNAME_RESOURCES`	`\|resources\|`
`Public FOLDERNAME_SCRIPT`	`\|src\|`
`Public FRAMENAME_CONTENT`	`\|contentFrame\|`
`Public FRAMENAME_VSID`	`\|vsidFrame\|`
`Public FRAMENAME_VSIDLIST`	`\|vsidListFrame\|`
`Public MSG_INVALID_SIGNATURE_CODE`	`\|The specified Signature code is invalid or resolves to conflicting Library, Class, Property, Method, or Modifier types. \|`
`Public SIGNATURE_VALUE_CLASS`	`1024`
`Public SIGNATURE_VALUE_CONST`	`8`
`Public SIGNATURE_VALUE_EVENT`	`128`
`Public SIGNATURE_VALUE_FINAL`	`16384`
`Public SIGNATURE_VALUE_FUNCTION`	`64`
`Public SIGNATURE_VALUE_GET`	`2`
`Public SIGNATURE_VALUE_LIBRARY`	`65536`
`Public SIGNATURE_VALUE_PRIVATE`	`4096`
`Public SIGNATURE_VALUE_PROPERTY`	`256`
`Public SIGNATURE_VALUE_PUBLIC`	`2048`
`Public SIGNATURE_VALUE_REMARK`	`1`
`Public SIGNATURE_VALUE_SET`	`4`
`Public SIGNATURE_VALUE_STATIC`	`8192`
`Public SIGNATURE_VALUE_SUB`	`32`
`Public SIGNATURE_VALUE_TYPE`	`512`
`Public SIGNATURE_VALUE_VARIABLE`	`16`
`Public SIGNATURE_VALUE_VSE`	`32768`
`Public SIGNATURE_VALUE_VSID`	`131072`
`Public SUMMARY_ROW_HEADER_CONSTANT`	`\|<tr><th class="colFirst">Name</th><th class="colOne">Value</th><th class="colLast">Comment</th></tr>\|`
`Public SUMMARY_ROW_HEADER_DEFAULT`	`\|<tr><th class="colFirst">Name</th><th class="colOne">Type</th><th class="colLast">Comment</th></tr>\|`

Classes Summary

CodeElement	Represents a block of code
Constant	Represents a Constant
Context	Context Carrier
ExceptionElement	Represents a single programmatic Exception
LabeledElement	Represents a single programmatic labeled element
Library	Represents a VoltScript Library
MajorElement	Represents a major code Object, such as a Class or a Library
Method	Represents a Method (Sub, Function, or Property)
ObjectClass	Represents an Object Class
ObjectType	Represents an Object Type
Project	Common base-level class for VSID Library or VSID VSE classes.
ValuedElement	Represents a single programmatic minor element (Constant, Variable, Argument, etc)
Variable	Represents a Variable
VSE	Represents a VoltScript Extension Object
VSID	Represents all VSEs / Libraries (and their children) in a VSID Database.
VSIDwriter	Writer Class for writing BaliScript documentation and source code files.

Method Summaries

`generateNavHTML(taggedValues As StringList, bsxstubid As String, includeHeader As Boolean) As StringQueue`
`generatePageHTML(taggedValues As StringList, apidoc As StringsCarrier, includeNavBar As Boolean) As StringQueue`
`getAdditionalPropertyKeys(code As Long) As Variant`
`getCodeElementInstanceType(instancecode As Long) As String`
`getElementsDetail(elements As Variant, elementtypename As String) As StringQueue`
`getElementSummary(elements As Variant, elementtypename As String) As StringQueue`
`getMajorElementsListItems(source As Variant, summarylinkprefix As String) As StringList`
`getMajorElementsUnorderedList(source As Variant, label As String, summarylinkprefix As String) As String`
`getMethodsDetail(source As Variant) As StringQueue`
`getMethodSummaries(source As Variant) As StringQueue`
`getSignatureCode(source As String) As Long`
`getSignatureElements(source As Library) As StringQueue`
`getSignatureModifiers(source As Long) As StringQueue`
`getValuedElementLinkedSummariesHTML(source As Variant, parent As CodeElement) As StringQueue`
`getVSIDstubContent(key As String) As StringsCarrierList`
`readTextFileToStringQueue(source As String) As StringQueue`
`signatureCodeToInstanceCode(signaturecode As Long) As Long`
`sortFQNbyLabel(source As Variant) As StringQueue`
`writeAPIdoc(taggedValues As StringList, source As StringQueue, target As String) As Long`
`getContext() As Context`
`getInstanceCodes() As Variant`
`getVSIDwriter() As VSIDwriter`

Methods Detail

generateNavHTML

Public Function generateNavHTML(taggedValues As StringList, bsxstubid As String, includeHeader As Boolean) As StringQueue
idx	Argument	Data Type	Attributes	Comments
1	taggedValues	StringList		values to replace tags in the various HTML stub (header, nav, footer, etc.) files
2	bsxstubid	String		Identifier for the BSX Stub HTML file to use.
3	includeHeader	Boolean		Flag indicating if the HTML_HEADER should be included.

generatePageHTML

Public Function generatePageHTML(taggedValues As StringList, apidoc As StringsCarrier, includeNavBar As Boolean) As StringQueue
Generates the final Page HTML content for the API documentation
idx	Argument	Data Type	Attributes	Comments
1	taggedValues	StringList		values to replace tags in the various HTML stub (header, nav, footer, etc.) files
2	apidoc	StringsCarrier		API documentation HTML content to be inserted into the final page HTML
3	includeNavBar	Boolean		Flag indicating if the Navigation Bars (HTML_NAVBAR_TOP, HTML_NAVBAR_BOTTOM should be included.

getAdditionalPropertyKeys

Public Function getAdditionalPropertyKeys(code As Long) As Variant
Gets additional property keys used for pulling information from a documen
idx	Argument	Data Type	Attributes	Comments
1	code	Long		Instance Code specifying the object instance type for which Property Keys should be retrieved: SIGNATURE_VALUE_VSE: Get Property Keys for VSE Ojbect Classes SIGNATURE_VALUE_LIBRARY: Get Property Keys for (Script) Library Object Classes. SIGNATURE_VALUE_TYPE: Get Property Keys for ObjectType instances

Throws Exceptions
Message	Error Code	Comments
MSG_PARAMETER_INVALID	1195	if instancecode% is not a valid instance type code

getCodeElementInstanceType

Public Function getCodeElementInstanceType(instancecode As Long) As String
Gets the Code Element Instance Type String for the specified instance code.
idx	Argument	Data Type	Attributes	Comments
1	instancecode	Long		Instance Code of the Code Element Supported Instance Codes: SIGNATURE_VALUE_CONST SIGNATUE_VALUE_VARIABLE SIGNATURE_VALUE_SUB SIGNATURE_VALUE_FUNCTION SIGNATURE_VALUE_EVENT SIGNATURE_VALUE_PROPERTY SIGNATURE_VALUE_TYPE SIGNATURE_VALUE_CLASS SIGNATURE_VALUE_VSE SIGNATURE_VALUE_LIBRARY SIGNATURE_VALUE_VSID SIGNATURE_VALUE_REMARK

getElementsDetail

Public Function getElementsDetail(elements As Variant, elementtypename As String) As StringQueue
Gets Element Detail html from an array of Element Objects.
idx	Argument	Data Type	Attributes	Comments
1	elements	Variant		Array of Element objects (Methods or Variables).
2	elementtypename	String		TypeName of the element (Method or Variable)

getElementSummary

Public Function getElementSummary(elements As Variant, elementtypename As String) As StringQueue
Gets Element Summaries from an array of Method, Variable, or Constant Objects.
idx	Argument	Data Type	Attributes	Comments
1	elements	Variant		Array of Element objects (Method, Variable, or Constant).
2	elementtypename	String		TypeName of the element (Method, Variable, or Constant)

getMajorElementsListItems

Public Function getMajorElementsListItems(source As Variant, summarylinkprefix As String) As StringList
Gets ListItems HTML from an array of MajorElements
idx	Argument	Data Type	Attributes	Comments
1	source	Variant		Array of MajorElements
2	summarylinkprefix	String		Prefix for the list item summary link

getMajorElementsUnorderedList

Public Function getMajorElementsUnorderedList(source As Variant, label As String, summarylinkprefix As String) As String
Gets UnorderedList HTML from an array of Major Elements
idx	Argument	Data Type	Attributes	Comments
1	source	Variant		Array of MajorElements
2	label	String		Label for the Unordered List
3	summarylinkprefix	String		Prefix for the list item summary link

getMethodsDetail

Public Function getMethodsDetail(source As Variant) As StringQueue
Gets Method Detail html from an array of Method Objects.
idx	Argument	Data Type	Attributes	Comments
1	source	Variant		Array of Method objects.

getMethodSummaries

Public Function getMethodSummaries(source As Variant) As StringQueue
Gets Method Summaries from an array of Method Objects.
idx	Argument	Data Type	Attributes	Comments
1	source	Variant		Array of Method objects.

getSignatureCode

Public Function getSignatureCode(source As String) As Long
Calculates the Signature Code for a given source string.
idx	Argument	Data Type	Attributes	Comments
1	source	String		String from which to generate the signature value

getSignatureElements

Public Function getSignatureElements(source As Library) As StringQueue
Returns a StringQueue containing the various Signature elements (Type, Class, Property, Sub, etc) for an associated value. Performs a bitwise comparison on the source value to determine the elements of the returned array Source value compared to the following constants: Const SIGNATURE_VALUE_GET = 1 Const SIGNATURE_VALUE_SET = 2 Const SIGNATURE_VALUE_SUB = 4 Const SIGNATURE_VALUE_FUNCTION = 8 Const SIGNATURE_VALUE_EVENT = 16 Const SIGNATURE_VALUE_PROPERTY = 32 Const SIGNATURE_VALUE_TYPE = 64 Const SIGNATURE_VALUE_CLASS = 128 Const SIGNATURE_VALUE_PUBLIC = 256 Const SIGNATURE_VALUE_PRIVATE = 512 Const SIGNATURE_VALUE_STATIC = 1024 Const SIGNATURE_VALUE_FINAL = 2048 Const SIGNATURE_VALUE_VSE = 4096 Const SIGNATURE_VALUE_LIBRARY = 8192 Const SIGNATURE_VALUE_VSID = 16384 The order of possible values to be returned is: VSID (standalone) VSE (standalone) Library (standalone) Static, Private, Public, Class, Type, Property, Event, Function, Sub, Set, Get For example, if the source value is 1313, then the array values returned are "Static", "Public", "Property", and "Get" (1024 + 256 + 32 + 1). If a conflict occurs with the returned value type (such as "Sub" and "Function", or "Get" and "Set") an error will be thrown.
idx	Argument	Data Type	Attributes	Comments
1	source	Library		Signature Code from which to generate the result

Throws Exceptions
Message	Error Code	Comments
MSG_INVALID_SIGNATURE_CODE	1195	if source is negative or resolves to conflicting results.

getSignatureModifiers

Public Function getSignatureModifiers(source As Long) As StringQueue
Returns a StringQueue containing the various Signature modifiers (Public, Private, Static, Final) for an associated value. Performs a bitwise comparison on the source value to determine the elements of the returned array Source value compared to the following constants: Const SIGNATURE_VALUE_GET = 1 Const SIGNATURE_VALUE_SET = 2 Const SIGNATURE_VALUE_SUB = 4 Const SIGNATURE_VALUE_FUNCTION = 8 Const SIGNATURE_VALUE_EVENT = 16 Const SIGNATURE_VALUE_PROPERTY = 32 Const SIGNATURE_VALUE_TYPE = 64 Const SIGNATURE_VALUE_CLASS = 128 Const SIGNATURE_VALUE_PUBLIC = 256 Const SIGNATURE_VALUE_PRIVATE = 512 Const SIGNATURE_VALUE_STATIC = 1024 Const SIGNATURE_VALUE_FINAL = 2048 Const SIGNATURE_VALUE_VSE = 4096 Const SIGNATURE_VALUE_LIBRARY = 8192 Const SIGNATURE_VALUE_VSID = 16384 The order of possible values to be returned is: Final, Static, Private, Public For example, if the source value is 1313, then the array values returned are "Static" and public "Public" (1024 + 256 + 32 + 1) (values for 32 and 1 are not returned) If a conflict occurs with the returned value type (such as "Public" and "Private") an error will be thrown.
idx	Argument	Data Type	Attributes	Comments
1	source	Long		Signature Code from which to generate the result

Throws Exceptions
Message	Error Code	Comments
MSG_INVALID_SIGNATURE_CODE	1195	if source is negative or resolves to conflicting results.

getValuedElementLinkedSummariesHTML

Public Function getValuedElementLinkedSummariesHTML(source As Variant, parent As CodeElement) As StringQueue
Gets ValuedElement Summaries from an array of ValuedElement Objects.
idx	Argument	Data Type	Attributes	Comments
1	source	Variant		Array of ValuedElement objects.
2	parent	CodeElement		Parent CodeElement to the source array

getVSIDstubContent

Public Function getVSIDstubContent(key As String) As StringsCarrierList
Gets a "singleton" instance of the VSID stub StringsCarrierList object for the associated key.
idx	Argument	Data Type	Attributes	Comments
1	key	String		Identifier used to specify which BSX stub StringsCarrierList to return

Throws Exceptions
Message	Error Code	Comments
MSG_PARAMETER_BLANK	1199	if key is blank.

readTextFileToStringQueue

Public Function readTextFileToStringQueue(source As String) As StringQueue
Reads the contents of a text file into a StringQueue
idx	Argument	Data Type	Attributes	Comments
1	source	String		Filepath of file to be read.

signatureCodeToInstanceCode

Public Function signatureCodeToInstanceCode(signaturecode As Long) As Long
Extracts an InstanceCode from a Signature Code
idx	Argument	Data Type	Attributes	Comments
1	signaturecode	Long		Signature Code from which to extract the Instance Code

sortFQNbyLabel

Public Function sortFQNbyLabel(source As Variant) As StringQueue
Sorts an Array of FQN values by the Label portion FQN = FQNPrefix.Label Sorts by Label.FQNPrefix
idx	Argument	Data Type	Attributes	Comments
1	source	Variant		Array of FQN Strings

writeAPIdoc

Public Function writeAPIdoc(taggedValues As StringList, source As StringQueue, target As String) As Long
Writes API documentation to a file Replaces moustache tag Generated by APIdoc (1.0.0) on Thu May 09 2024 at 16:00:38 in source with API documentation Generation Text. API documentation Generation Text: "Generated by APIdoc (APIDOC_VERSION) on <TIMESTAMP> --> IMPORTANT NOTE: Existing files will be OVERWRITTEN! It is up to the calling code to pre-check for existence of file.
idx	Argument	Data Type	Attributes	Comments
1	taggedValues	StringList		values to replace tags in the various HTML stub (header, nav, footer, etc.) files
2	source	StringQueue		Text to be written to a file.
3	target	String		Filepath of file to be written.

Throws Exceptions
Message	Error Code	Comments
MSG_PARAMETER_BLANK	1199	if taggedValues is Nothing.
MSG_PARAMETER_BLANK	1199	if target filepath is blank.
MSG_OPERATION_FAILED	1100	if other file system exception on failure.

getContext

Static Public Function getContext() As Context
Gets the Context Object instance

getInstanceCodes
Static Public Function getInstanceCodes() As Variant
Gets Instance Codes for CodeElement instance types (VSID, VSE, Library, Class, Type, Property, Event, Function, Sub)

Static Public Function getInstanceCodes() As Variant
Gets Instance Codes for CodeElement instance types (VSID, VSE, Library, Class, Type, Property, Event, Function, Sub)

getVSIDwriter
Static Public Function getVSIDwriter() As VSIDwriter
Gets the VSIDwriter object for the session.

Library BSXdocumentationUtils

VSID.BSXdocumentationUtils

Library Summary

Constants

Classes Summary

Method Summaries

Methods Detail

generateNavHTML

generatePageHTML

getAdditionalPropertyKeys

getCodeElementInstanceType

getElementsDetail

getElementSummary

getMajorElementsListItems

getMajorElementsUnorderedList

getMethodsDetail

getMethodSummaries

getSignatureCode

getSignatureElements

getSignatureModifiers

getValuedElementLinkedSummariesHTML

getVSIDstubContent

readTextFileToStringQueue

signatureCodeToInstanceCode

sortFQNbyLabel

writeAPIdoc

getContext

getInstanceCodes

getVSIDwriter